Amiga Format CD 44/Amiga Format CD44 (1999-08-26)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-10].iso/-in_the_mag-/basics/ace/nap.lha/NAP.guide

Amigaguide Document | 1997-05-19 | 20KB | 495 lines

@database "NAP/NAP.guide"
@master "NAP/NAP.dok"
@node Main "Introduction"
@TOC Inhaltsverzeichnis
@NEXT Aufruf
 @{"NAP - New ACE Preprocessor" link Inhaltsverzeichnis}                              @{"Version 2.02" link History}
 --------------------------                              ------------
 Introduction
 NAP is a preprocessor for the programming language  ACE  (AmigaBASIC
 Compiler with Extras)  by David  Benn.  By  publishing this  version
 there are all in all three preprocessors for ACE:
  (1) APP
      The official preprocessor from the ACE release. It removes ACE
      comments and includes files via @{"#INCLUDE" link Direktiven}.
  (2) ACPP
      The ACE-Version of the C preprocessor CPP.  The only difference
      is that the path for the include files is ACE:. The strength of
      this  preprocessor  is  the  supporting  of  all   preprocessor
      @{"commands" link direktiven}. Furthermore it removes C comments.
  (3) NAP
      This preprocessor is especially for  ACE.  It recognizes almost
      all (inclusive the most important ones)  @{"preprocessor commands" LINK Direktiven},
      removes  ACE  comments as well as  C comments and has even some
      special functions.
                                                      @{"Daniel Seifert" link autor}
                                Berlin-Hellersdorf, May 19th, 1997
@endnode
@node Inhaltsverzeichnis "AmigaGUIDE Manual for NAP 2.02"
@TOC Inhaltsverzeichnis
@PREV Main
@NEXT Benutzung
 |\   |       |
|       |
|                        Version 2.02
 | \  |       |____|       |____|                         05-19-1997
 |  \ |       |    |       |
 |   \| e w   |    | C E   |     r e p r o c e s s o r
 Table of contents:
 @{"Introduction" link Main}
 @{"How to use" link Benutzung}
 @{"How to start" link Aufruf}
 @{"Options" link Optionen}
 @{"Preprocessor commands" link Direktiven}
 @{"Known bugs" link bugs}
 @{"Future versions" link future}
 @{"Thanks" link greetings}
 @{"Copyright" link Copyright}
 @{"About the autor" link autor}
 @{"History" link history}
 @{"Quit" quit}
 P.S.:
  Actions NAP does and some special things are explained in the corr-
  esponding chapters of @{"OPTIONS" link optionen}
@endnode
@node Escape
@TOC Inhaltsverzeichnis
 Should you have ever the wish  to stop  NAP  you just have to  press
 CTRL-C.
@endnode
@node Benutzung
@TOC Inhaltsverzeichnis
@PREV Inhaltsverzeichnis
@NEXT Aufruf
@TITLE "How to use"
 Copy the new version to ACE:BIN/
 Just replace in your bas script the call of APP or ACPP through NAP.
 The parameters are the same. Should there be options you have to re-
 move them or to replace them by the corresponding @{"ones of NAP" link optionen}.
 If you are using  AIDE  by Herbert Breuer you just have to enter NAP
 in the  "Precompiler" Section under  "other"  and to save the config
 file.
@endnode
@node Aufruf
@TOC Inhaltsverzeichnis
@PREV Benutzung
@NEXT Optionen
@TITLE "How to call"
 You can skip the first paragraph if you are using AIDE:
 NAP can only be launched from the CLI/Shell. It needs a minimum of 2
 parameters: the input and the output file. NAP can't read/write from
 or to standard input/output.
 Pay attention that NAP deletes the output file when it opens it.
 Furthermore you can pass @{"options" link optionen} to NAP.  They must be introduced by
 a hyphen  ("-").  If an option needs an additional parameter it must
 follow  directly  (without spaces)  the corresponding option letter.
 After the parameter there must be a space!
 Of course you can write -tz as well as @{"-t" link OptionT} @{"-z" link OptionZ}.
@endnode
@node Optionen
@TOC Inhaltsverzeichnis
@PREV Aufruf
@NEXT Buffer
@TITLE Options
 Options
  Options are not case sensitive. But be aware that tokens are!
  @{"-b<kB>" link Buffer}                   set buffersize in kilobytes
  @{"-d<token>[<=value>]" link OptionD}      define a token
  @{"-p<path>" link Includepath}                 set path for include files
  @{"-u<token>" link OptionU}                undef a token
  @{"-c" link OptionC}   :   don't remove comments
  @{"-e" link OptionE}   :   suppress error messages
  @{"-h" link OptionH}   :   help
  @{"-i" link OptionI}   :   ignore @{"#Define" link Direktiven}s
  @{"-l" link OptionL}   :   sum empty lines
  @{"-q" link OptionQ}   :   @{"#Define" link Direktiven}s to CONST
  @{"-s" link OptionS}   :   remove unused structs
  @{"-t" link OptionT}   :   tracing
  @{"-x" link OptionX}   :   comment source code
  @{"-z" link OptionZ}   :   elapsed time
@endnode
@node OptionX "-x"
@TOC Inhaltsverzeichnis
@PREV OptionT
@NEXT OptionZ
 NAP now allows you to comment the source code, e.g. it writes single
 line comments ( ' ) into the preprocessed source code  stating which
 line and which  (include) file is processed right now.  This happens
 only if a new file is included.
 These comments are removed properly by the ACE compiler  so there is
 no need to ran  RemoveLine  after it  as it would be necessary  when
 using ACPP.
 This function is useful when ACE reports an error.  And as it is not
 easy to keep track of which part of the preprocessed source code be-
 longs to which file  these comments might help.  But be aware of the
 fact  that the  line numbers may be wrong  as it is count  how  many
 lines are read in but not, how many have been cut (empty lines, pre-
 processor commands, comments, ...).
@endnode
@node Buffer
@TOC Inhaltsverzeichnis
@PREV Optionen
@NEXT OptionD
 To speed NAP up  I wrote a routine which replaces ACE's INPUT# comm-
 and. This routine is much faster due to buffered reading. The buffer
 has a defaultsize of 102400 bytes (100 kB)  and exist for every open
 file.  But the buffer is  never greater  than the file (so we do not
 waste memory)
 Best is if NAP can always write the whole file into the buffer.  100
 kB should be enough for this. But you are allowed to set the buffer-
 size up to a size of 640 kB (this source code I don't want to debug)
 If you do not have enough memory  you  can set the buffer size to  a
 smaller size.
@endnode
@node OptionD "-d<token>[=value]"
@TOC Inhaltsverzeichnis
@PREV Buffer
@NEXT IncludePath
 Same as if you wrote within the source
        @{"#DEFINE" link Direktive} <token> <value>
 If you don't pass <=value>, <value> is 1.
@endnode
@node Includepath "-p<path>"
@TOC Inhaltsverzeichnis
@PREV OptionD
@NEXT OptionU
 Herewith you specify in which path the include files are. Three
 paths are already defined:  ACEINCLUDE:
                             ACE:
                             ACE:INCLUDE/
 I recommened to use always the logical device ACEINCLUDE: !!!
@endnode
@node OptionU "-u<token>"
@TOC Inhaltsverzeichnis
@PREV IncludePath
@NEXT OptionC
 Same as if you wrote within the source
        @{"#UNDEF" link Direktiven} <token>
@endnode
@node OptionC "-c"
@TOC Inhaltsverzeichnis
@PREV OptionU
@NEXT OptionE
 If you use this option  NAP  does not remove comments  but does just
 replace C comments through ACE ones  (so there won't be any problems
 when compiling).
@endnode
@node OptionE "-e"
@TOC Inhaltsverzeichnis
@PREV OptionC
@NEXT OptionH
 By using this option  NAP does suppress  ANY error messages  whether
 they lead to a break  or not  (even "file not found" errors  are not
 printed but be aware of the results when compiling!)
@endnode
@node OptionH "-h"
@TOC Inhaltsverzeichnis
@PREV OptionE
@NEXT OptionI
 Prints a help text.
@endnode
@node OptionI "-i"
@TOC Inhaltsverzeichnis
@PREV OptionH
@NEXT OptionL
 By using this options @{"#DEFINE" LINK Direktiven}s are ignored.
@endnode
@node OptionL "-l"
@TOC Inhaltsverzeichnis
@PREV OptionI
@NEXT OptionQ
 As default NAP does sum up empty lines (real empty lines: lines with
 just one space are not an empty line!). By using this option you are
 telling NAP not to do this anymore!
@endnode
@node OptionQ "-q"
@TOC Inhaltsverzeichnis
@PREV OptionL
@NEXT OptionS
 Defines aren't processed entirely when using this function  but just
 converted to ACE's CONST commands!  Be aware that this may result in
 errors when including files with structures  containing elements ala
 NODEPTR  (#DEFINE NODEPTR ADDRESS)  which will lead  to errors  when
 compiling!
 Pay attention, that you can't pass parameters if you use this option
 to defines!
@endnode
@node OptionS "-s"
@TOC Inhaltsverzeichnis
@PREV OptionQ
@NEXT OptionT
 This option switches on the most interesting function of NAP :-)))))
 NAP does now remove unused structures.
 If you do not understand  why removing of unused structures is good,
 take a look at GadTools.b. Now type
                ACPP GadTools.b ram:tg_acpp.b <RETURN>
                NAP -s GadTools.b ram:gt_nap.b <RETURN>
 Recognized? Yeah, gt_na.b is smaller and faster to compile. But why:
 Just type:
                NAP -st GadTools.b ram:gt_nap.b <RETURN>
 By using option -t you switch on the tracing. At the end of the out-
 put you seen how NAP is listing the structures which are needed and
 which are not.
 As GadTools.b is using dozens of include files there are all at all
 about 110 structures! But not even 20 are needed ...
 And,  by the way,  for people having less memory  removing about 90
 structures is very helpful.
@endnode
@node OptionT "-t"
@TOC Inhaltsverzeichnis
@PREV OptionS
@NEXT OptionX
 Traces the work of NAP (very interesting, just take a look!)
 You get to know:
    - names of the include files, inclusive filenumbers
    - structures (definition, declaration, use) when using @{"-s" Link OptionS}
@endnode
@node OptionT "-z"
@TOC Inhaltsverzeichnis
@PREV OptionX
@NEXT Direktiven
 When using this option NAP will print the time  needed to precompile
 the input file.
@endnode
@node Direktiven
@TOC Inhaltsverzeichnis
@PREV OptionT
@NEXT Bugs
 NAP supports the following commands:
           IF
           IF DEFINED
           IFDEF
           IFNDEF
           ELSE
           ELIF (same as ELSE IF, but NAP does not support ELSE IF!)
           ENDIF
           INCLUDE
           DEFINE
           UNDEF
 Not supported:
           PRAGMA
           ASSERT
           DEBUG
           NODEBUG
           ERROR
 Here a short explanation for the supported ones:
  In general, a preprocessor command is introduced by a # at the very
  beginning of a line. Most commands need an additional parameter.
  -------
  IF <expression>
  <expression>  is a  @{"mathematical term" link mathAusdruck}.  If it's true (not zero) the
  next part (until #ELIF, #ELSE, #ENDIF) will be processed, otherwise
  ignored. IF commands may be nested.
  -------
  IF DEFINED <token> or IFDEF <token>
  Is true, if <token> has been defined.
  -------
  IFNDEF <token>
  Is true, if <token> has NOT been defined.
  -------
  ELSE
  Must follow an  IF or  ELIF command.  The next part is processed if
  the expression at the last IF command has been false. Pay attention
  that there must be only one ELSE command  within an IF command  but
  that NAP does not check!
  -------
  ELIF <expression>
  Combination of "ELSE IF". Pay attention to the fact that ELIF isn't
  implemented very well! Errors when using ELIF are very probable!
  -------
  ENDIF
  Ends an IF command.
  -------
  INCLUDE <filename>
  The < and > MUST really be at the begin and the end of the filename.
  By using this command,  <filename>  is included at this position of
  the file.
  -------
  DEFINE <token> <value>
  Defines <token> as <value>. By writing "#DEFINE one 1" will lead to
  replace "one" by "1" throughout the following part of the source
  code.
  Pay attention that <token> IS case sensitive! "One", "one", "ONE"
  and "oNe" are different tokens!!!
  Of course you can pass parameters. Add to <token> (without spaces!)
  a list of parameters enclosed in brackets and use the same parame-
  ter names within <value>.
  Example:      #DEFINE box(x1,y1,x2,y2) LINE (x1,y1)-(x2,y2),,b
                box(10,10,100,200)
                --> LINE (10,10)-(100,200)
  If <value> is very large you may split it in several lines by using
  "\" or "~". This can always be done, not only in #DEFINE.
  Note: When using macros (defines with parameters) be aware that the
        passed parameters between two commas/parantheses MUST NOT be
        any other char than alphanumerical ones!
        =>      box(10, 10, 100, 200)           won't work
        =>      box(1+1,10,100,200)             won't work
        =>      box(getval("x-pos"),10,100,200) won't work
        =>      ...
        This is a bug in the parser routine. It is necessary to re-
        write the whole routine. I'll try to have done it the next
        version.
  -------
  UNDEF <token>
  Undo a DEFINE <token>
@endnode
@node mathAusdruck
@TITLE "Mathematical Expression of the IF and ELIF command"
@TOC Inhaltsverzeichnis
@PREV Direktiven
@NEXT Direktiven
 NAP supports +, -, *, \, / and ().
 The result is always SINGLE!!  Therefore: 1/3 * 3 -1 = -0.000001 in-
 stead of 0 as it would be correct.
 If you want to use hexadecimal numbers or binary numbers use the ACE
 specific prefixes (&H, ...)
@endnode
@node bugs
@TOC Inhaltsverzeichnis
@PREV Direktiven
@NEXT Future
@TITLE "Known bugs"
 * See @{"mathematical expression" link mathAusdruck}
 * ELIF commands are very very buggy! I recommened not to use them.
   Same with ELSE if you use it with ELIF. Otherwise ELSE does work
   correctly.
 * If structures are only refered to via SIZEOF but if they are not
   declared, neither direct nor indirect, NAP removes them.
   HELP: just declare the structure via
               DECLARE STRUCT <struct-name> *dummyptr
 * Some of the include files contain { } statements which are NOT
   comments (C-language's { and } are like PASCALS BEGIN and END!)
   This may cause errors!!!!
   i.e.:  (1)  /*
               #DEFINE InitAnimKey(key) { *(key) = NULL }
               */
               will lead to a single line containing a "}" !!!
               As there is no "{" before ....
          (2)  "#DEFINE testsub { ... }" will lead to "#DEFINE
               testsub "
          (3)  ...
   If you have problems like the above ones you should check the
   include files.
   I just do not have any idea how to fix these problems. Actually
   I don't care about it really as { } ARE comments and this should
   be paid attention to in the include files of ACE. Anyway, per-
   haps replacing { and } by BLOCK and END BLOCK would help ?!
 * Using macros which parameters containing parentheses are passed
   to will cause errors:
     #INCLUDE <ACE/ACEdef.h>
     SetTag(GTLV_Labels,SADD("test"))
   won't be processed correctly. Replacing SADD by @ might help here
   but in general it's a big problem I'll try to fix ASAP.
   Same applies if there's a non-alphanumerical char in the parameter!!!
 If you find more bugs, please contact @{"me" link autor} !!! See @{"History" link history} for already
 removed bugs.
@endnode
@node future
@TOC Inhaltsverzeichnis
@PREV bugs
@NEXT Greetings
@TITLE "Future versions"
 * removing of the @{"bugs" link bugs}
 * more preprocessor commands
 * more options (see ACPP's manual)
 * speed increasing (although NAP has become faster and faster)
 * ...
 Of course I am interested in your ideas.  If  you have some,  please
 contact @{"me" link autor}.       TIA.
@endnode
@node greetings
@TOC Inhaltsverzeichnis
@PREV future
@NEXT Copyright
@TITLE "Thanks and Greetings"
 Thanks to ...
  David Benn,  Author of ACE, for his help and tips for some problems
  as well as for having developed ACE.
  Herbert Breuer for his help at the  assembler routines  and for his
  hints and tips.  Furthermore  thanks  for spending his time testing
  NAP. All found bugs (except the ones I found) are found by him.
  (No wonder  since he is the  one and only user of  NAP.  Or all the
   other ones does not pay attention to the section @{"Coypright" link Copyright} :(
  all the users,  who are going to use NAP and does not pay attention
  to eventual @{"bugs" link bugs}.
@endnode
@node Copyright
@TOC Inhaltsverzeichnis
@PREV Greetings
@NEXT Autor
 NAP - New ACE Preprocessor                              Version 2.02
                                                          05-19-1997
 This version of  NAP as well as the @{"previous ones" link history} are copyright
 @{"Daniel Seifert" link autor}.
 NAP is Cardware.  This means that the @{"author" link autor} just wants ONE postcard
 from each user (perhaps with an extra beautiful stamp :) and the in-
 formation how the user likes NAP.
 All who do this are allowed to copy and spread NAP (but without ear-
 ning money!). Doing this all files must stay unaltered and together!
 Changes  of  the  source  code are only permissible for the own use.
 Spreading changed versions is NOT allowed!!! (But who thinks to have
 changed/add/improved something important can contact me and I'll see
 to put it in the next version)
 The use of  NAP's sub modules  (especially ones from  NAP_Mods.b) in
 own programs is only allowed  if no  money  is  earned.  Furthermore
 there must be a statement in the source code as well as in the manu-
 al that this routine is  still  copyright  @{"Daniel Seifert" link autor}.  Eventual
 changes must be marked! It would be nice if the one would inform me.
 Since version 2.02 the source code is not longer within the package!
 Disassembling is strongly forbidden.
   Although NAP has been tested there is no warranty that it works
   correctly. You use NAP on your own risk. The author can't be
   made liable for eventual damages.
                                                       Daniel Seifert
                                                         05-19-1997
@endnode
@node Autor
@TOC Inhaltsverzeichnis
@PREV Copyright
@NEXT History
@TITLE Author
My name is Daniel Seifert and I'm born in 1978. At the moment I'm
studying  at  the  "1st  Grammar  School  Hellersdorf"  (Leonard-
Bernstein-Gymnasium) whereas Hellersdorf is the eastermost suburb
of Berlin  which is the capital of Germany, as you probably know,
don't you?
My favourite subjects are Maths, English and,  of course,  compu-
ting.
If you want to contact me, there are three possibilities:
 (a) E-Mail (preferred, except for the picture card! :-)
     You can reach me at my school: [e-mail]
                                    -----------------------------
     Please  give  me  some  time to answer -> holidays, exams or
     problems with the school computer (no Amiga :(
     After June '98 this EMail address might have gone (hm, well,
     if not I'll have a little problem ;-)  so use the snail mail
     address instead to ask for my  new address  (or look out for
     new programs by me ;-)
     WWW
     Well, as  of  now  I do not have my own home page :-( But if
     you are interested in a (German) math corner, which I helped
     to create, take a look at :
            http://members.aol.com/fuzzymathe/index.htm
 (b) snail mail
     Please do only expect an answer if you enclose  some  money
     for my costs (postage, ...). I am a little bit out of money
     (aren't student always ? ;-)) so I just don't want to spend
     my money on this.
     (Err, I almost forgot my address ;-)
              Daniel Seifert
              Elsenborner Weg 25
              12621 Berlin
              GERMANY
 (c) telephone
     Well, I cannot imagine that anybody wants to contact me
     this way. But anyway: call ([phone] and ask
     for Daniel.                      ^ Berlin
                                 ^ Germany (?)
Happy ACEing ;)
@endnode
@node History
@TOC Inhaltsverzeichnis
@PREV Autor
 See @{"German Manual" link NAP_(d).guide/History}
@endnode